home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
CD ROM Paradise Collection 4
/
CD ROM Paradise Collection 4 1995 Nov.iso
/
program
/
bstrng11.zip
/
BSTRING.DOC
< prev
next >
Wrap
Text File
|
1995-01-28
|
14KB
|
511 lines
BSTRING PROGRAMMER'S MANUAL
VERSION 1.0
TechniLib Company
Copyright 1995, by TechniLib (TM) Company
All Rights Reserved
TERMS OF USE AND DISTRIBUTION
BSTRING is a shareware product; therefore, unregistered copies of BSTRING
are made available free of charge so that potential purchasers will have the
opportunity to examine and test the software before committing payment.
Distribution of unregistered copies of BSTRING to other potential users is
also permitted and appreciated. However, usage and distribution of BSTRING
must conform to the following conditions. In the following statement, the
term "commercial distribution," includes shareware distribution.
1) BSTRING and accompanying software must be distributed together in copies of
the original archive provided by TechniLib. Neither the archive nor
individual files therein may be modified.
2) The BSTRING archive may be distributed in combination with other shareware
products; however, the BSTRING archive may not be distributed with other
commercially distributed software without written consent of TechniLib.
3) Copies of BSTRING which have been used to develop software for commercial
distribution must be registered before such software is marketed. Copies of
BSTRING which have been used to develop noncommercial software must be
registered if such software is to be regularly used either by the developer or
others.
4) Commercially distributed software must embed BSTRING procedures in the
software code. Files contained in the BSTRING archive may not be placed in
the distribution media.
5) BSTRING is designed to offer a set of services to other executable code.
BSTRING may not be used to develop software for commercial distribution which
will essentially offer any of these same services to other executable code.
Exceptions to this condition require written consent of TechniLib.
6) Rights afforded by registering a single copy of BSTRING pertain only to a
single computer.
7) BSTRING may be registered for a fee of $10.00 per copy. Consult README.DOC
in the BSTRING archive for further instructions regarding registration.
DISCLAIMER OF WARRANTY
BSTRING AND ALL ACCOMPANYING SOFTWARE AND LITERATURE ARE DISTRIBUTED WITH
THE EXCLUSION OF ANY AND ALL IMPLIED WARRANTIES, AND WITH THE EXCLUSION OF
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. TechniLib
SHALL HAVE NO LIABILITY FOR SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
RESULTING FROM THE USE OF BSTRING OR ACCOMPANYING MATERIALS. The user assumes
the entire risk of using this software.
Copyright 1995, by TechniLib (TM) Company
All Rights Reserved
Introduction
------------
Though BASIC is not among the most powerful programming languages, it
does have the some of the most powerful string handling capabilities of all
languages. BSTRING is a library of C functions which emulate the string
functions in BASIC. Therefore, BSTRING not only provides a set of powerful
functions to C, but also simplifies the transition to C from BASIC.
All procedures in BSTRING are written in assembly language. BSTRING
functions are therefore very compact and very fast. In fact, they are faster
than analogous string functions in standard C libraries. Speed improvements
are even more pronounced on Pentium processors because BSTRING code is
designed to fully utilize the superscalar architecture.
The BSTRING archive includes libraries for both Microsoft C and Borland
C. Microsoft libraries are contained in MICROSOF.ZIP. Borland libraries are
in BORLAND.ZIP.
To use BSTRING, the programmer should include the BSTRING.H header file
in their C program, and should link the program with the appropriate BSTRING
library. The appropriate library will depend upon the memory model being
used. The following is a list of available BSTRING libraries matched with
their corresponding memory models.
Library Memory Model
------------ ------------
BSTRINGS.LIB Small
BSTRINGC.LIB Compact
BSTRINGM.LIB Medium
BSTRINGL.LIB Large and Huge
1
Detailed Specifications
-----------------------
This section presents detailed descriptions of the various string
functions in BSTRING. Each description includes a BASIC equivalent to the
BSTRING function. These descriptions use variables which would be declared as
follows:
BASIC:
DIM sstring AS STRING, dstring AS STRING
DIM start AS INTEGER, n AS INTEGER, ShortInt AS INTEGER, ASCIIcode as integer
DIM LongInt AS LONG
DIM DoubleFloat as DOUBLE
C:
char sstring[.], dstring[.]; /* Dimensions must be supplied */
int start, n, ShortInt, ASCIIcode;
long LongInt;
double DoubleFloat;
dstring is used in all of the following descriptions as the destination
string. sstring is used as the source string. If the destination string may
be modified by the function, then the function will always return the pointer
to this string. The source string is never modified provided that it is
stored at a different location than the destination. All BSTRING functions
are designed such that the source string and destination string may be equal.
Copy Strings
------------
BASIC: dstring = sstring
C: movstr(dstring, sstring);
PROTOTYPE: char* movstr(char* dstring, char* sstring);
Compute String Length
---------------------
BASIC: ShortInt = LEN(sstring)
C: ShortInt = len(sstring);
PROTOTYPE: int len(char* sstring);
DETAILS: len returns 0 if sstring is null.
2
Add Strings
-----------
BASIC: dstring = dstring + sstring
C: addstr(dstring, sstring);
PROTOTYPE: char* addstr(char* dstring, char* sstring);
BASIC: dstring = sstring + dstring
C: addstrr(dstring, sstring); /* Add string reverse */
PROTOTYPE: char* addstrr(char* dstring, char* sstring);
Get Characters from Left or Right of String
-------------------------------------------
BASIC: dstring = LEFT$(sstring, n)
C: left(dstring, sstring, n);
PROTOTYPE: char* left(char* dstring, char* sstring, int n);
BASIC: dstring = RIGHT$(sstring, n)
C: right(dstring, sstring, n);
PROTOTYPE: char* right(char* dstring, char* sstring, int n);
DETAILS: If n = 0 (an invalid value), both left and right set dstring to null.
If n >= len(sstring), both left and right return dstring = sstring.
Get Characters Embedded in String
---------------------------------
BASIC: dstring = MID$(sstring, start, n)
C: mid(dstring, sstring, start, n);
BASIC: dstring = MID$(sstring, start)
C: mid(dstring, sstring, start, -1);
PROTOTYPE: char* mid(char* dstring, char* sstring, int start, int n);
DETAILS: mid sets dstring to the n characters of sstring beginning with the
start character position. Character positions are numbered 1 and upward. If
sstring does not contain n characters from the start position, dstring is
terminated with the last character of sstring.
If start = 0 or n = 0 (invalid values), mid sets dstring to null. If start
> len(sstring), mid sets dstring to null.
Under C++, either or both of start and n may be omitted. If omitted, start
defaults to 1, and n defaults to -1 (0xffff).
3
Compare Strings
---------------
BASIC: ShortInt = (dstring <= sstring) - (dstring >= sstring)
C: ShortInt = cmpstr(dstring, sstring);
PROTOTYPE: int cmpstr(char* dstring, char* sstring);
DETAILS: cmpstr compares dstring to sstring. If the strings are equal, cmpstr
returns 0. If dstring is greater, cmpstr returns 1. If sstring is greater,
cmpstr returns -1. Neither string is modified.
Search for Substring
--------------------
BASIC: ShortInt = INSTR(start, sstring, substring)
C: ShortInt = instr(sstring, substring, start);
BASIC: ShortInt = INSTR(sstring, substring)
C: ShortInt = instr(sstring, substring, 1);
PROTOTYPE: int instr(char* sstring, char* substring, int start);
DETAILS: instr searches sstring for an occurrence of substring. The search
begins at the character position supplied in start (first character = 1). If
substring is found, instr returns the character position at which substring
begins. Character positions are numbered 1 upward. If substring is not
found, instr returns 0.
If start = 0 (an invalid value), instr returns 0. If start > len(sstring),
instr returns 0. If substring is null, instr returns start.
Under C++, start may be omitted, in which event, start defaults to 1.
Compute Value of Numeric String
-------------------------------
BASIC: LongInt = VAL(sstring)
C: LongInt = val(sstring);
PROTOTYPE: long val(char* sstring);
BASIC: LongInt = VAL(sstring);
C: LongInt = valh(sstring); /* sstring is hexadecimal */
PROTOTYPE: long valh(char* sstring);
BASIC: DoubleFloat = VAL(sstring);
C: DoubleFloat = vald(sstring);
PROTOTYPE: double vald(char* sstring);
DETAILS: val will accept a hexadecimal string provided that it is prefixed
with 0x or 0X (e.g. 0xffff). valh assumes a hexadecimal string with no
prefix. Hexadecimal strings may use either upper or lower case letters.
vald will accept either standard or scientific notation. vald uses numeric
processor instructions; therefore, a numeric processor must either be present
or an emulator must be installed.
4
Convert Numeric to String
-------------------------
BASIC: dstring = STR$(LongInt)
C: str(dstring, LongInt);
PROTOTYPE: char* str(char* dstring, long intnum);
BASIC: dstring = HEX$(LongInt);
C: hex(dstring, LongInt);
PROTOTYPE: char* hex(char* dstring, long intnum);
BASIC: dstring = STR$(DoubleFloat)
C: strd(dstring, DoubleFloat, n);
C: strds(dstring, DoubleFloat, n);
PROTOTYPE: char* strd(char* dstring, double floatval, int decimals);
PROTOTYPE: char* strds(char* dstring, double floatval, int decimals);
DETAILS: hex always returns a string 8 characters long. The digits will
always be upper case. No prefix is appended to the string.
strd returns dstring in standard notation whereas strds returns dstring in
scientific notation. n specifies the number of decimal places. For strds, n
specifies the number of decimal places in the mantissa. strd cannot accept
numbers that are absolutely greater than or equal to 10 ^ 18. In such cases,
the function will return dstring = "E" thereby indicating that strds must be
used. strd and strds use numeric processor instructions; therefore, a numeric
processor must either be present or an emulator must be installed.
Remove Spaces from Right or Left of String
------------------------------------------
BASIC: dstring = LTRIM$(sstring)
C: ltrim(dstring, sstring);
PROTOTYPE: char* ltrim(char* dstring, char* sstring);
BASIC: dstring = RTRIM$(sstring)
C: rtrim(dstring, sstring);
PROTOTYPE: char* rtrim(char* dstring, char* sstring);
Return String of Spaces
-----------------------
BASIC: dstring = SPACE$(n);
C: space(dstring, n);
PROTOTYPE: char* space(char* dstring, int n);
DETAILS: If n = 0 (invalid value), dstring is returned as null.
5
Return String of Repeated Character
-----------------------------------
BASIC: dstring = STRING$(n, ASCIIcode)
C: string(dstring, n, ASCIIcode);
PROTOTYPE: char* string(char* dstring, int n, int asciicode);
DETAILS: If n = 0 (invalid value), dstring is returned as null.
Convert String to Lower or Upper Case
-------------------------------------
BASIC: dstring = LCASE$(sstring)
C: lcase(dstring, sstring);
PROTOTYPE: char* lcase(char* dstring, char* sstring);
BASIC: dstring = UCASE$(sstring)
C: ucase(dstring, sstring);
PROTOTYPE: char* ucase(char* dstring, char* sstring);
Justify String Within Fixed Field
---------------------------------
BASIC: dstring = SPACE$(n): LSET dstring = sstring
C: lset(dstring, sstring, n);
PROTOTYPE: char* lset(char* dstring, char* sstring, int n);
BASIC: dstring = SPACE$(n): RSET dstring = sstring
C: rset(dstring, sstring, n);
PROTOTYPE: char* rset(char* dstring, char* sstring, int n);
DETAILS: dstring is always returned with length n. sstring is left-justified
or right-justified within dstring. The remainder of dstring is filled with
spaces. If len(sstring) >= n, both lset and rset return dstring =
left(sstring, n).
If n = 0 (invalid value), dstring is returned as null.
Observe that the LSET and RSET functions in BASIC implicitly set n =
len(dstring).
6